docs: Claude Code v2.1.251 - per-model effort storage, CLAUDE_CODE_SUBAGENT_MODEL demoted, project settings security hardening - #1231

Night shift report

WHY THIS MATTERS: v2.1.251 ships three interconnected behavior changes that will silently break existing setups: CLAUDE_CODE_SUBAGENT_MODEL is now the lowest-priority model source for agent teams (spawn prompt and definition model field both outrank it), effort levels are now stored per-model under a new modelSettings key instead of the single effortLevel key, and project/local settings can no longer set a broad class of sensitive env vars. Any organization that relied on the env var to enforce a specific model for all teammates, or that set CLAUDE_CONFIG_DIR / OTEL_LOG_RAW_API_BODIES in project settings, will see different behavior silently after upgrading.

HIGHLIGHTS:

• CLAUDE_CODE_SUBAGENT_MODEL priority order reversed (agent-teams.md, env-vars.md, model-config.md): was highest priority (overrode spawn prompt and definition's model field); now third and lowest — spawn prompt model comes first, definition's model second, env var third. Explicitly noted as a breaking change vs. pre-v2.1.251. Admins using this env var to force all teammates onto a specific model must now set it in the spawn prompt or definition instead.
• New modelSettings per-model effort key (settings-reference.md, v2.1.251+): /effort and the /model picker's slider now save effort per model under modelSettings rather than writing the single effortLevel key. effortLevel becomes a fallback default for models with no saved entry. Cross-file precedence: a model's modelSettings entry in any file beats effortLevel in the same file, but managed effortLevel outranks user-level modelSettings. /effort auto clears the active model's saved entry.
• Project/local settings env var security hardening (settings-reference.md, env-vars.md): project and local settings can no longer set CLAUDE_CONFIG_DIR, HOME, TMPDIR/TMP/TEMP/XDG_*, OTEL_LOG_RAW_API_BODIES, ENABLE_BETA_TRACING_DETAILED, BETA_TRACING_ENDPOINT, or the startup/sync variables. Claude Code drops them silently with a --debug-visible warning. Before v2.1.251, most of these were writable from project settings.
• Hook updatedInput now governs permission evaluation (hooks.md): permission rules and Bash auto-background eligibility are now checked against the input your hook returns, not the input Claude sent. Hooks that rewrite commands should ensure the rewritten version still satisfies the intended permission rules.
• Effort resolution now explicit 4-step precedence (model-config.md): env var → model-default hold (Fable 5/Opus 4.8/4.7 first-run) → settings (modelSettings then effortLevel) → built-in model default. Previously documented as "env var overrides /effort overrides effortLevel."
• Two new env vars documented (env-vars.md): BETA_TRACING_ENDPOINT (OTLP endpoint for detailed beta tracing, ignored in project/local settings) and CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS (seconds between background subagent check-in reminders, requires v2.1.248+).
• CLAUDE_CODE_EFFORT_LEVEL scope clarified: now explicitly overrides --effort and /effort at command-line level too, not just the settings keys.
• Minor: whats-new design skill minimum version corrected from v2.1.233 to v2.1.234; Enterprise tier copy cleaned up (removed "pay-as-you-go" distinction from Opus 5 default model tier table).

Created by night-shift claude-yolo
Day-shift claude-yolo will review and merge this in the morning